package com.example.mapper;

import com.example.entity.DiskFiles;

import org.apache.ibatis.annotations.Param;
import org.apache.ibatis.annotations.Select;
import org.apache.ibatis.annotations.Update;

import java.util.List;

/**
 * 磁盘文件数据访问层接口
 *
 * 主要职责：
 * 1. 管理文件/文件夹元数据（CRUD操作）
 * 2. 提供多维度查询能力（按文件夹、日期、用户等）
 * 3. 维护文件层级关系（树形结构查询）
 * 4. 处理软删除逻辑（delete标记过滤）
 */
public interface DiskFilesMapper {

    /**
     * 新增磁盘文件记录
     *
     * @param diskFiles 要插入的文件/文件夹信息对象（包含文件名、类型、父目录等元数据）
     * @return {@link int} 受影响的行数（通常1表示成功，0表示失败）
     *
     * @implNote 自动生成create_time/update_time时间戳
     */
    int insert(DiskFiles diskFiles);

    /**
     * 根据ID逻辑删除文件记录
     *
     * @param id 文件记录ID（主键）
     * @return {@link int} 受影响的行数（软删除操作，仅更新delete标记字段）
     *
     * @implNote 执行UPDATE操作设置delete=1，保留历史记录
     */
    int deleteById(Integer id);

    /**
     * 根据ID更新文件记录
     *
     * @param diskFiles 包含更新信息的文件对象（必须包含ID字段）
     * @return {@link int} 受影响的行数（0表示未找到记录或数据未变更）
     *
     * @implNote 自动更新update_time时间戳
     */
    int updateById(DiskFiles diskFiles);

    /**
     * 根据ID查询文件记录
     *
     * @param id 文件记录ID（主键）
     * @return {@link DiskFiles} 对应的文件对象（未找到返回null）
     *
     * @implNote 返回对象包含完整文件元数据（含文件哈希值/存储路径等）
     */
    DiskFiles selectById(Integer id);

    /**
     * 条件查询文件记录
     *
     * @param diskFiles 查询条件对象（支持按文件名/类型/创建时间等过滤）
     * @return {@link List<DiskFiles>} 符合条件的文件记录列表（自动过滤已删除记录）
     *
     * @implNote 支持动态SQL条件拼接，默认按update_time降序排列
     */
    List<DiskFiles> selectAll(DiskFiles diskFiles);

    /**
     * 查询所有文件记录
     *
     * @param diskFiles 查询条件对象
     * @return {@link List<DiskFiles>} 所有文件记录列表（包含已删除标记的记录）
     *
     * @implNote 用于系统管理界面，显示完整文件历史记录
     */
    List<DiskFiles> selectAllData(DiskFiles diskFiles);

    /**
     * 根据文件夹ID查询直接子文件
     *
     * @param folderId 父文件夹ID（0表示根目录）
     * @return {@link List<DiskFiles>} 指定文件夹下的直接子文件列表（不包含子文件夹内容）
     *
     * @implNote 返回结果按file_name字母顺序排序
     */
    List<DiskFiles> selectByFolderId(Integer folderId);

    /**
     * 查询文件夹下所有层级文件（包含子文件夹内容）
     *
     * @param folderId 父文件夹ID（0表示根目录）
     * @return {@link List<DiskFiles>} 指定文件夹下所有层级的文件列表（递归查询）
     *
     * @implNote 使用递归CTE实现多层级查询（需数据库支持）
     */
    List<DiskFiles> selectAllByFolderId(Integer folderId);

    /**
     * 按日期统计文件创建数量
     *
     * @param date 日期字符串（格式：yyyy-MM-dd，匹配create_time字段）
     * @return {@link Integer} 当天创建的文件总数（包含所有类型）
     *
     * @implNote 使用LIKE进行日期范围查询（实际执行时会自动添加%通配符）
     */
    @Select("select count(*) from disk_files where crate_time like concat('%', #{date}, '%')")
    Integer selectByDate(String date);

    /**
     * 查询用户的根文件夹集合
     *
     * @param userId 用户ID（关联用户文件系统）
     * @return {@link List<DiskFiles>} 用户对应的根文件夹列表（type='folder'且未删除）
     *
     * @implNote 过滤条件：
     * - type = 'folder'
     * - delete = 0
     * - folder_id IS NULL（顶级节点）
     */
    @Select("SELECT * FROM disk_files WHERE type = 'folder' AND user_id = #{userId} AND `delete` = 0")
    List<DiskFiles> findRootFolders(@Param("userId") Integer userId);

    /**
     * 根据父节点ID查询子文件/文件夹
     *
     * @param Id     父节点ID（文件夹ID）
     * @param userId 用户ID（关联用户文件系统）
     * @return {@link List<DiskFiles>} 指定父节点下的子文件/文件夹列表（未删除）
     *
     * @implNote 过滤条件：
     * - folder_id = #{Id}
     * - delete = 0
     * - 按文件类型(type)区分文件夹/文件
     */
    @Select("SELECT * FROM disk_files WHERE folder_id = #{Id} AND user_id = #{userId} AND `delete` = 0")
    List<DiskFiles> findChildren(@Param("Id") Integer Id, @Param("userId") Integer userId);
}